home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / man.n / scan.n < prev    next >
Text File  |  1995-07-17  |  10KB  |  331 lines
  1. '\"
  2. '\" Copyright (c) 1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/scan.n,v 1.3 93/08/04 17:18:42 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .\" The definitions below are for supplemental macros used in Tcl/Tk
  24. .\" manual entries.
  25. .\"
  26. .\" .HS name section [date [version]]
  27. .\"    Replacement for .TH in other man pages.  See below for valid
  28. .\"    section names.
  29. .\"
  30. .\" .AP type name in/out [indent]
  31. .\"    Start paragraph describing an argument to a library procedure.
  32. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  33. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  34. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  35. .\"    needed;  use .AS below instead)
  36. .\"
  37. .\" .AS [type [name]]
  38. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  39. .\"    name are examples of largest possible arguments that will be passed
  40. .\"    to .AP later.  If args are omitted, default tab stops are used.
  41. .\"
  42. .\" .BS
  43. .\"    Start box enclosure.  From here until next .BE, everything will be
  44. .\"    enclosed in one large box.
  45. .\"
  46. .\" .BE
  47. .\"    End of box enclosure.
  48. .\"
  49. .\" .VS
  50. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  51. .\"    of man pages.
  52. .\"
  53. .\" .VE
  54. .\"    End of vertical sidebar.
  55. .\"
  56. .\" .DS
  57. .\"    Begin an indented unfilled display.
  58. .\"
  59. .\" .DE
  60. .\"    End of indented unfilled display.
  61. .\"
  62. '\"    # Heading for Tcl/Tk man pages
  63. .de HS
  64. .ds ^3 \\0
  65. .if !"\\$3"" .ds ^3 \\$3
  66. .if '\\$2'cmds'       .TH \\$1 1 \\*(^3 \\$4
  67. .if '\\$2'lib'        .TH \\$1 3 \\*(^3 \\$4
  68. .if '\\$2'tcl'        .TH \\$1 n \\*(^3 Tcl "Tcl Built-In Commands"
  69. .if '\\$2'tk'         .TH \\$1 n \\*(^3 Tk "Tk Commands"
  70. .if '\\$2'tclc'        .TH \\$1 3 \\*(^3 Tcl "Tcl Library Procedures"
  71. .if '\\$2'tkc'         .TH \\$1 3 \\*(^3 Tk "Tk Library Procedures"
  72. .if '\\$2'tclcmds'         .TH \\$1 1 \\*(^3 Tk "Tcl Applications"
  73. .if '\\$2'tkcmds'         .TH \\$1 1 \\*(^3 Tk "Tk Applications"
  74. .if t .wh -1.3i ^B
  75. .nr ^l \\n(.l
  76. .ad b
  77. ..
  78. '\"    # Start an argument description
  79. .de AP
  80. .ie !"\\$4"" .TP \\$4
  81. .el \{\
  82. .   ie !"\\$2"" .TP \\n()Cu
  83. .   el          .TP 15
  84. .\}
  85. .ie !"\\$3"" \{\
  86. .ta \\n()Au \\n()Bu
  87. \&\\$1    \\fI\\$2\\fP    (\\$3)
  88. .\".b
  89. .\}
  90. .el \{\
  91. .br
  92. .ie !"\\$2"" \{\
  93. \&\\$1    \\fI\\$2\\fP
  94. .\}
  95. .el \{\
  96. \&\\fI\\$1\\fP
  97. .\}
  98. .\}
  99. ..
  100. '\"    # define tabbing values for .AP
  101. .de AS
  102. .nr )A 10n
  103. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  104. .nr )B \\n()Au+15n
  105. .\"
  106. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  107. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  108. ..
  109. '\"    # BS - start boxed text
  110. '\"    # ^y = starting y location
  111. '\"    # ^b = 1
  112. .de BS
  113. .br
  114. .mk ^y
  115. .nr ^b 1u
  116. .if n .nf
  117. .if n .ti 0
  118. .if n \l'\\n(.lu\(ul'
  119. .if n .fi
  120. ..
  121. '\"    # BE - end boxed text (draw box now)
  122. .de BE
  123. .nf
  124. .ti 0
  125. .mk ^t
  126. .ie n \l'\\n(^lu\(ul'
  127. .el \{\
  128. .\"    Draw four-sided box normally, but don't draw top of
  129. .\"    box if the box started on an earlier page.
  130. .ie !\\n(^b-1 \{\
  131. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  132. .\}
  133. .el \}\
  134. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  135. .\}
  136. .\}
  137. .fi
  138. .br
  139. .nr ^b 0
  140. ..
  141. '\"    # VS - start vertical sidebar
  142. '\"    # ^Y = starting y location
  143. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  144. .de VS
  145. .mk ^Y
  146. .ie n 'mc \s12\(br\s0
  147. .el .nr ^v 1u
  148. ..
  149. '\"    # VE - end of vertical sidebar
  150. .de VE
  151. .ie n 'mc
  152. .el \{\
  153. .ev 2
  154. .nf
  155. .ti 0
  156. .mk ^t
  157. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  158. .sp -1
  159. .fi
  160. .ev
  161. .\}
  162. .nr ^v 0
  163. ..
  164. '\"    # Special macro to handle page bottom:  finish off current
  165. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  166. '\"    # page bottom macro.
  167. .de ^B
  168. .ev 2
  169. 'ti 0
  170. 'nf
  171. .mk ^t
  172. .if \\n(^b \{\
  173. .\"    Draw three-sided box if this is the box's first page,
  174. .\"    draw two sides but no top otherwise.
  175. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  176. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  177. .\}
  178. .if \\n(^v \{\
  179. .nr ^x \\n(^tu+1v-\\n(^Yu
  180. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  181. .\}
  182. .bp
  183. 'fi
  184. .ev
  185. .if \\n(^b \{\
  186. .mk ^y
  187. .nr ^b 2
  188. .\}
  189. .if \\n(^v \{\
  190. .mk ^Y
  191. .\}
  192. ..
  193. '\"    # DS - begin display
  194. .de DS
  195. .RS
  196. .nf
  197. .sp
  198. ..
  199. '\"    # DE - end display
  200. .de DE
  201. .fi
  202. .RE
  203. .sp .5
  204. ..
  205. .HS scan tcl
  206. .BS
  207. '\" Note:  do not modify the .SH NAME line immediately below!
  208. .SH NAME
  209. scan \- Parse string using conversion specifiers in the style of sscanf
  210. .SH SYNOPSIS
  211. \fBscan \fIstring format varName \fR?\fIvarName ...\fR?
  212. .BE
  213.  
  214. .SH INTRODUCTION
  215. .PP
  216. This command parses fields from an input string in the same fashion
  217. as the ANSI C \fBsscanf\fR procedure and returns a count of the number
  218. of fields sucessfully parsed.
  219. \fIString\fR gives the input to be parsed and \fIformat\fR indicates
  220. how to parse it, using \fB%\fR conversion specifiers as in \fBsscanf\fR.
  221. Each \fIvarName\fR gives the name of a variable; when a field is
  222. scanned from \fIstring\fR the result is converted back into a string
  223. and assigned to the corresponding variable.
  224.  
  225. .SH "DETAILS ON SCANNING"
  226. .PP
  227. \fBScan\fR operates by scanning \fIstring\fR and \fIformatString\fR together.
  228. If the next character in \fIformatString\fR is a blank or tab then it
  229. is ignored.
  230. Otherwise, if it isn't a \fB%\fR character then it 
  231. must match the next non-white-space character of \fIstring\fR.
  232. When a \fB%\fR is encountered in \fIformatString\fR, it indicates
  233. the start of a conversion specifier.
  234. A conversion specifier contains three fields after the \fB%\fR:
  235. a \fB*\fR, which indicates that the converted value is to be discarded 
  236. instead of assigned to a variable; a number indicating a maximum field
  237. width; and a conversion character.
  238. All of these fields are optional except for the conversion character.
  239. .PP
  240. When \fBscan\fR finds a conversion specifier in \fIformatString\fR, it
  241. first skips any white-space characters in \fIstring\fR.
  242. Then it converts the next input characters according to the 
  243. conversion specifier and stores the result in the variable given
  244. by the next argument to \fBscan\fR.
  245. The following conversion characters are supported:
  246. .TP 10
  247. \fBd\fR
  248. The input field must be a decimal integer.
  249. It is read in and the value is stored in the variable as a decimal string.
  250. .TP 10
  251. \fBo\fR
  252. The input field must be an octal integer. It is read in and the 
  253. value is stored in the variable as a decimal string.
  254. .TP 10
  255. \fBx\fR
  256. The input field must be a hexadecimal integer. It is read in 
  257. and the value is stored in the variable as a decimal string.
  258. .TP 10
  259. \fBc\fR
  260. A single character is read in and its binary value is stored in 
  261. the variable as a decimal string.
  262. Initial white space is not skipped in this case, so the input
  263. field may be a white-space character.
  264. This conversion is different from the ANSI standard in that the
  265. input field always consists of a single character and no field
  266. width may be specified.
  267. .TP 10
  268. \fBs\fR
  269. The input field consists of all the characters up to the next 
  270. white-space character; the characters are copied to the variable.
  271. .TP 10
  272. \fBe\fR or \fBf\fR or \fBg\fR
  273. The input field must be a floating-point number consisting 
  274. of an optional sign, a string of decimal digits possibly con
  275. taining a decimal point, and an optional exponent consisting 
  276. of an \fBe\fR or \fBE\fR followed by an optional sign and a string of 
  277. decimal digits.
  278. It is read in and stored in the variable as a floating-point string.
  279. .TP 10
  280. \fB[\fIchars\fB]
  281. The input field consists of any number of characters in 
  282. \fIchars\fR.
  283. The matching string is stored in the variable.
  284. If the first character between the brackets is a \fB]\fR then
  285. it is treated as part of \fIchars\fR rather than the closing
  286. bracket for the set.
  287. .TP 10
  288. \fB[^\fIchars\fB]
  289. The input field consists of any number of characters not in 
  290. \fIchars\fR.
  291. The matching string is stored in the variable.
  292. If the character immediately following the \fB^\fR is a \fB]\fR then it is 
  293. treated as part of the set rather than the closing bracket for 
  294. the set.
  295. .LP
  296. The number of characters read from the input for a conversion is the
  297. largest number that makes sense for that particular conversion (e.g.
  298. as many decimal digits as possible for \fB%d\fR, as 
  299. many octal digits as possible for \fB%o\fR, and so on).
  300. The input field for a given conversion terminates either when a
  301. white-space character is encountered or when the maximum field 
  302. width has been reached, whichever comes first.
  303. If a \fB*\fR is present in the conversion specifier 
  304. then no variable is assigned and the next scan argument is not consumed.
  305.  
  306. .SH "DIFFERENCES FROM ANSI SSCANF"
  307. .PP
  308. The behavior of the \fBscan\fR command is the same as the behavior of
  309. the ANSI C \fBsscanf\fR procedure except for the following differences:
  310. .IP [1]
  311. .VS
  312. \fB%p\fR and \fB%n\fR conversion specifiers are not currently
  313. supported.
  314. .VE
  315. .IP [2]
  316. For \fB%c\fR conversions a single character value is
  317. converted to a decimal string, which is then assigned to the
  318. corresponding \fIvarName\fR;
  319. no field width may be specified for this conversion.
  320. .IP [3]
  321. .VS
  322. The \fBl\fR, \fBh\fR, and \fBL\fR modifiers are ignored;  integer
  323. values are always converted as if there were no modifier present
  324. and real values are always converted as if the \fBl\fR modifier
  325. were present (i.e. type \fBdouble\fR is used for the internal
  326. representation).
  327. .VE
  328.  
  329. .SH KEYWORDS
  330. conversion specifier, parse, scan
  331.